11.4 User-Defined Units

Calc provides ways to get quick access to your selected “favorite” units, as well as ways to define your own new units.

To select your favorite units, store a vector of unit names or expressions in the Calc variable Units. The u 1 through u 9 commands (calc-quick-units) provide access to these units. If the value on the top of the stack is a plain number (with no units attached), then u 1 gives it the specified units. (Basically, it multiplies the number by the first item in the Units vector.) If the number on the stack does have units, then u 1 converts that number to the new units. For example, suppose the vector ‘[in, ft]’ is stored in Units. Then 30 u 1 will create the expression ‘30 in’, and u 2 will convert that expression to ‘2.5 ft’.

The u 0 command accesses the tenth element of Units. Only ten quick units may be defined at a time. If the Units variable has no stored value (the default), or if its value is not a vector, then the quick-units commands will not function. The s U command is a convenient way to edit the Units variable; see Operations on Variables.

The u d (calc-define-unit) command records the units expression on the top of the stack as the definition for a new, user-defined unit. For example, putting ‘16.5 ft’ on the stack and typing u d rod defines the new unit ‘rod’ to be equivalent to 16.5 feet. The unit conversion and simplification commands will now treat rod just like any other unit of length. You will also be prompted for an optional English description of the unit, which will appear in the Units Table. If you wish the definition of this unit to be displayed in a special way in the Units Table buffer (such as with an asterisk to indicate an approximate value), then you can call this command with an argument, C-u u d; you will then also be prompted for a string that will be used to display the definition.

The u u (calc-undefine-unit) command removes a user-defined unit. It is not possible to remove one of the predefined units, however.

If you define a unit with an existing unit name, your new definition will replace the original definition of that unit. If the unit was a predefined unit, the old definition will not be replaced, only “shadowed.” The built-in definition will reappear if you later use u u to remove the shadowing definition.

To create a new fundamental unit, use either 1 or the unit name itself as the defining expression. Otherwise the expression can involve any other units that you like (except for composite units like ‘mfi’). You can create a new composite unit with a sum of other units as the defining expression. The next unit operation like u c or u v will rebuild the internal unit table incorporating your modifications. Note that erroneous definitions (such as two units defined in terms of each other) will not be detected until the unit table is next rebuilt; u v is a convenient way to force this to happen.

Temperature units are treated specially inside the Calculator; it is not possible to create user-defined temperature units.

The u p (calc-permanent-units) command stores the user-defined units in your Calc init file (the file given by the variable calc-settings-file, typically ~/.emacs.d/calc.el), so that the units will still be available in subsequent Emacs sessions. If there was already a set of user-defined units in your Calc init file, it is replaced by the new set. (See General Mode Commands, for a way to tell Calc to use a different file for the Calc init file.)